<?php

/**
 * @author Tongle Xu <xutongle@gmail.com>
 * @copyright Copyright (c) 2003-2103 Jinan TintSoft development co., LTD
 * @license http://www.tintsoft.com/html/about/copyright/
 * @version $Id$
 */
namespace Leaps\Api;

use Leaps;
use Leaps\Base\InvalidRouteException;

/**
 * 控制台应用程序。
 *
 * Application extends from [[Leaps\Base\Application]] by providing
 * functionalities that are
 * specific to console requests. In particular, it deals with console requests
 * through a command-based approach:
 *
 * - A console application consists of one or several possible user commands;
 * - Each user command is implemented as a class extending
 * [[\Leaps\Console\Controller]];
 * - User specifies which command to run on the command line;
 * - The command processes the user request with the specified parameters.
 *
 * The command classes reside in the directory specified by [[controllerPath]].
 * Their naming should follow the same naming convention as controllers. For
 * example, the `help` command
 * is implemented using the `HelpController` class.
 *
 * To run the console application, enter the following on the command line:
 *
 * ~~~
 * yii <route> [--param1=value1 --param2 ...]
 * ~~~
 *
 * where `<route>` refers to a controller route in the form of
 * `ModuleID/ControllerID/ActionID`
 * (e.g. `sitemap/create`), and `param1`, `param2` refers to a set of named
 * parameters that
 * will be used to initialize the controller action (e.g. `--since=0` specifies
 * a `since` parameter
 * whose value is 0 and a corresponding `$since` parameter is passed to the
 * action method).
 *
 * A `help` command is provided by default, which lists available commands and
 * shows their usage.
 * To use this command, simply type:
 *
 * ~~~
 * Leaps help
 * ~~~
 *
 * @property Response $response The response component. This property is
 *           read-only.
 *
 * @author Tongle Xu <xutongle@gmail.com>
 * @since 4.0
 */
class Application extends \Leaps\Base\Application {

	/**
	 * 这个应用程序的默认路由。
	 * @var string
	 */
	public $defaultRoute = 'index';

	/**
	 * 控制器类的命名空间。
	 * @var string the namespace that controller classes are in. If not set,
	 * it will use the "app\controller" namespace.
	 */
	public $controllerNamespace = 'app\\api';

	/**
	 * 当前活动的控制器实例
	 * @var Controller
	 */
	public $controller;

	/**
	 * 初始化应用
	 */
	public function init() {
		parent::init ();
	}

	/**
	 * 处理特定的请求。
	 *
	 * @param Request $request the request to be handled
	 * @return Response the resulting response
	 */
	public function handleRequest($request) {
		list ( $route, $params ) = $request->resolve ();
		$this->requestedRoute = $route;
		$result = $this->runAction ( $route, $params );
		if ($result instanceof Response) {
			return $result;
		} else {
			$response = $this->getResponse ();
			$response->exitStatus = ( int ) $result;
			return $response;
		}
	}

	/**
	 * 返回响应组件。
	 *
	 * @return Response the response component
	 */
	public function getResponse() {
		return $this->getComponent ( 'response' );
	}

	/**
	 * 从指定的路由运行一个控制器动作。
	 * This method parses the specified route and creates the corresponding
	 * child module(s), controller and action
	 * instances.
	 * It then calls [[Controller::runAction()]] to run the action with the
	 * given parameters.
	 * If the route is empty, the method will use [[defaultRoute]].
	 *
	 * @param string $route the route that specifies the action.
	 * @param array $params the parameters to be passed to the action
	 * @return integer the status code returned by the action execution. 0 means
	 *         normal, and other values mean abnormal.
	 * @throws Exception if the route is invalid
	 */
	public function runAction($route, $params = []) {
		try {
			return parent::runAction ( $route, $params );
		} catch ( InvalidRouteException $e ) {
			throw new Exception ( Leaps::t ( 'leaps', 'Unknown command "{command}".', [ 'command' => $route ] ), 0, $e );
		}
	}



	/**
	 * 注册核心应用程序组件。
	 *
	 * @see setComponents
	 */
	public function registerCoreComponents() {
		parent::registerCoreComponents ();
		$this->setComponents ( [ 'request' => [ 'class' => 'Leaps\Api\Request' ],'response' => [ 'class' => 'Leaps\Api\Response' ] ] );
	}
}
